home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / lib / perl5 / Moose / Role.pm < prev    next >
Encoding:
Perl POD Document  |  2010-07-25  |  7.5 KB  |  302 lines

  1. package Moose::Role;
  2. use strict;
  3. use warnings;
  4.  
  5. use Scalar::Util 'blessed';
  6. use Carp         'croak';
  7.  
  8. use Sub::Exporter;
  9.  
  10. our $VERSION   = '1.09';
  11. $VERSION = eval $VERSION;
  12. our $AUTHORITY = 'cpan:STEVAN';
  13.  
  14. use Moose       ();
  15. use Moose::Util ();
  16.  
  17. use Moose::Exporter;
  18. use Moose::Meta::Role;
  19. use Moose::Util::TypeConstraints;
  20.  
  21. sub extends {
  22.     croak "Roles do not support 'extends' (you can use 'with' to specialize a role)";
  23. }
  24.  
  25. sub with {
  26.     Moose::Util::apply_all_roles( shift, @_ );
  27. }
  28.  
  29. sub requires {
  30.     my $meta = shift;
  31.     croak "Must specify at least one method" unless @_;
  32.     $meta->add_required_methods(@_);
  33. }
  34.  
  35. sub excludes {
  36.     my $meta = shift;
  37.     croak "Must specify at least one role" unless @_;
  38.     $meta->add_excluded_roles(@_);
  39. }
  40.  
  41. sub has {
  42.     my $meta = shift;
  43.     my $name = shift;
  44.     croak 'Usage: has \'name\' => ( key => value, ... )' if @_ == 1;
  45.     my %options = ( definition_context => Moose::Util::_caller_info(), @_ );
  46.     my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
  47.     $meta->add_attribute( $_, %options ) for @$attrs;
  48. }
  49.  
  50. sub _add_method_modifier {
  51.     my $type = shift;
  52.     my $meta = shift;
  53.     my $code = pop @_;
  54.  
  55.     for (@_) {
  56.         croak "Roles do not currently support "
  57.             . ref($_)
  58.             . " references for $type method modifiers"
  59.             if ref $_;
  60.         my $add_method = "add_${type}_method_modifier";
  61.         $meta->$add_method( $_, $code );
  62.     }
  63. }
  64.  
  65. sub before { _add_method_modifier('before', @_) }
  66.  
  67. sub after  { _add_method_modifier('after',  @_) }
  68.  
  69. sub around { _add_method_modifier('around', @_) }
  70.  
  71. # see Moose.pm for discussion
  72. sub super {
  73.     return unless $Moose::SUPER_BODY;
  74.     $Moose::SUPER_BODY->(@Moose::SUPER_ARGS);
  75. }
  76.  
  77. sub override {
  78.     my $meta = shift;
  79.     my ( $name, $code ) = @_;
  80.     $meta->add_override_method_modifier( $name, $code );
  81. }
  82.  
  83. sub inner {
  84.     croak "Roles cannot support 'inner'";
  85. }
  86.  
  87. sub augment {
  88.     croak "Roles cannot support 'augment'";
  89. }
  90.  
  91. Moose::Exporter->setup_import_methods(
  92.     with_meta => [
  93.         qw( with requires excludes has before after around override )
  94.     ],
  95.     as_is => [
  96.         qw( extends super inner augment ),
  97.         \&Carp::confess,
  98.         \&Scalar::Util::blessed,
  99.     ],
  100. );
  101.  
  102. sub init_meta {
  103.     shift;
  104.     my %args = @_;
  105.  
  106.     my $role = $args{for_class};
  107.  
  108.     unless ($role) {
  109.         require Moose;
  110.         Moose->throw_error("Cannot call init_meta without specifying a for_class");
  111.     }
  112.  
  113.     my $metaclass = $args{metaclass} || "Moose::Meta::Role";
  114.  
  115.     # make a subtype for each Moose class
  116.     role_type $role unless find_type_constraint($role);
  117.  
  118.     # FIXME copy from Moose.pm
  119.     my $meta;
  120.     if ($role->can('meta')) {
  121.         $meta = $role->meta();
  122.  
  123.         unless ( blessed($meta) && $meta->isa('Moose::Meta::Role') ) {
  124.             require Moose;
  125.             Moose->throw_error("You already have a &meta function, but it does not return a Moose::Meta::Role");
  126.         }
  127.     }
  128.     else {
  129.         $meta = $metaclass->initialize($role);
  130.  
  131.         $meta->add_method(
  132.             'meta' => sub {
  133.                 # re-initialize so it inherits properly
  134.                 $metaclass->initialize( ref($_[0]) || $_[0] );
  135.             }
  136.         );
  137.     }
  138.  
  139.     return $meta;
  140. }
  141.  
  142. 1;
  143.  
  144. __END__
  145.  
  146. =pod
  147.  
  148. =head1 NAME
  149.  
  150. Moose::Role - The Moose Role
  151.  
  152. =head1 SYNOPSIS
  153.  
  154.   package Eq;
  155.   use Moose::Role; # automatically turns on strict and warnings
  156.  
  157.   requires 'equal';
  158.  
  159.   sub no_equal {
  160.       my ($self, $other) = @_;
  161.       !$self->equal($other);
  162.   }
  163.  
  164.   # ... then in your classes
  165.  
  166.   package Currency;
  167.   use Moose; # automatically turns on strict and warnings
  168.  
  169.   with 'Eq';
  170.  
  171.   sub equal {
  172.       my ($self, $other) = @_;
  173.       $self->as_float == $other->as_float;
  174.   }
  175.  
  176. =head1 DESCRIPTION
  177.  
  178. The concept of roles is documented in L<Moose::Manual::Roles>. This document
  179. serves as API documentation.
  180.  
  181. =head1 EXPORTED FUNCTIONS
  182.  
  183. Moose::Role currently supports all of the functions that L<Moose> exports, but
  184. differs slightly in how some items are handled (see L</CAVEATS> below for
  185. details).
  186.  
  187. Moose::Role also offers two role-specific keyword exports:
  188.  
  189. =over 4
  190.  
  191. =item B<requires (@method_names)>
  192.  
  193. Roles can require that certain methods are implemented by any class which
  194. C<does> the role.
  195.  
  196. Note that attribute accessors also count as methods for the purposes
  197. of satisfying the requirements of a role.
  198.  
  199. =item B<excludes (@role_names)>
  200.  
  201. Roles can C<exclude> other roles, in effect saying "I can never be combined
  202. with these C<@role_names>". This is a feature which should not be used
  203. lightly.
  204.  
  205. =back
  206.  
  207. =head2 B<unimport>
  208.  
  209. Moose::Role offers a way to remove the keywords it exports, through the
  210. C<unimport> method. You simply have to say C<no Moose::Role> at the bottom of
  211. your code for this to work.
  212.  
  213. =head2 B<< Moose::Role->init_meta(for_class => $role, metaclass => $metaclass) >>
  214.  
  215. The C<init_meta> method sets up the metaclass object for the role
  216. specified by C<for_class>. It also injects a a C<meta> accessor into
  217. the role so you can get at this object.
  218.  
  219. The default metaclass is L<Moose::Meta::Role>. You can specify an
  220. alternate metaclass with the C<metaclass> parameter.
  221.  
  222. =head1 METACLASS
  223.  
  224. When you use Moose::Role, you can specify which metaclass to use:
  225.  
  226.     use Moose::Role -metaclass => 'My::Meta::Role';
  227.  
  228. You can also specify traits which will be applied to your role metaclass:
  229.  
  230.     use Moose::Role -traits => 'My::Trait';
  231.  
  232. This is very similar to the attribute traits feature. When you do
  233. this, your class's C<meta> object will have the specified traits
  234. applied to it. See L<Moose/Metaclass and Trait Name Resolution> for more
  235. details.
  236.  
  237. =head1 APPLYING ROLES
  238.  
  239. In addition to being applied to a class using the 'with' syntax (see
  240. L<Moose::Manual::Roles>) and using the L<Moose::Util> 'apply_all_roles'
  241. method, roles may also be applied to an instance of a class using
  242. L<Moose::Util> 'apply_all_roles' or the role's metaclass:
  243.  
  244.    MyApp::Test::SomeRole->meta->apply( $instance );
  245.  
  246. Doing this creates a new, mutable, anonymous subclass, applies the role to that,
  247. and reblesses. In a debugger, for example, you will see class names of the
  248. form C< Class::MOP::Class::__ANON__::SERIAL::6 >, which means that doing a 'ref'
  249. on your instance may not return what you expect. See L<Moose::Object> for 'DOES'.
  250.  
  251. Additional params may be added to the new instance by providing 'rebless_params'.
  252. See L<Moose::Meta::Role::Application::ToInstance>.
  253.  
  254. =head1 CAVEATS
  255.  
  256. Role support has only a few caveats:
  257.  
  258. =over 4
  259.  
  260. =item *
  261.  
  262. Roles cannot use the C<extends> keyword; it will throw an exception for now.
  263. The same is true of the C<augment> and C<inner> keywords (not sure those
  264. really make sense for roles). All other Moose keywords will be I<deferred>
  265. so that they can be applied to the consuming class.
  266.  
  267. =item *
  268.  
  269. Role composition does its best to B<not> be order-sensitive when it comes to
  270. conflict resolution and requirements detection. However, it is order-sensitive
  271. when it comes to method modifiers. All before/around/after modifiers are
  272. included whenever a role is composed into a class, and then applied in the order
  273. in which the roles are used. This also means that there is no conflict for
  274. before/around/after modifiers.
  275.  
  276. In most cases, this will be a non-issue; however, it is something to keep in
  277. mind when using method modifiers in a role. You should never assume any
  278. ordering.
  279.  
  280. =back
  281.  
  282. =head1 BUGS
  283.  
  284. See L<Moose/BUGS> for details on reporting bugs.
  285.  
  286. =head1 AUTHOR
  287.  
  288. Stevan Little E<lt>stevan@iinteractive.comE<gt>
  289.  
  290. Christian Hansen E<lt>chansen@cpan.orgE<gt>
  291.  
  292. =head1 COPYRIGHT AND LICENSE
  293.  
  294. Copyright 2006-2010 by Infinity Interactive, Inc.
  295.  
  296. L<http://www.iinteractive.com>
  297.  
  298. This library is free software; you can redistribute it and/or modify
  299. it under the same terms as Perl itself.
  300.  
  301. =cut
  302.